.TH LIBPFM 3  "November, 2003" "" "Linux Programmer's Manual"
.SH NAME
libpfm \- a helper library to program the hardware performance counters of IA-64 CPUs
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.SH DESCRIPTION
The libpfm library is a helper library which can be used by applications to program
the IA-64 Performance Monitoring Unit (PMU). While it is being developed on Linux 
in conjunction with the Linux/ia64 subsystem. It is generic enough to be used on
other IA-64 operating systems. It is important to realize that the library does
not make the actual kernel calls to program the PMU, it simply helps you  figure
out which PMU registers to use to measure certains events. On Linux/ia64, for 
instance, it does not make any \fBperfmonctl\fR call.

There are two categories of PMU registers. The performance monitoring data registers (PMD) 
are used to collects counts or serve as hardware buffers. The performance monitoring control 
registers (PMCS) are used to indicate what events need to be monitored. Programming the PMU 
consists in setting up the PMC registers to monitor certain events. The PMDS are commonly set 
to zero unless sampling is used.

The number of PMC and PMD registers varies from one implementation of the IA-64
architecture to another. The association of PMC to PMD can also change. Moreover
the number and encoding of events can also widely change. Finally, the structure
of a PMC register can also change. All these factors make it quite difficult to 
write monitoring tools. 

This library is designed to simplify the programming of the PMC registers by hiding
the complexity behind simple interfaces. The library does this without limiting 
accessibility to model specific features by using a layered design.

The library is structured in two layers. The common layer provides an interface
that is shared by all implementations. For instance, getting an event descriptor using
the event name is the same operation on all IA-64 implementation, even though the returned
descriptor and the event name can vary.  This layer is good enough to setup simple monitoring
sessions which count occurrences of simple events. Then there is a model specific layer which 
gives access to the model-specific features. For instance, on Itanium, you can use the library
to figure out how to initialize PMC12 which controls the Branch Trace Buffer. Model 
specific interfaces have the abbreviated PMU model name in their names. For instance, 
\fBpfm_ita2_get_event_umask()\fR is an Itanium2 (ita2) specific function. 

When the library is initialized, it automatically probes the host CPU and enables the right 
set of interfaces. The layered design uses a modular implementation, where support for each
CPU is well separated and can be compiled in or out of the library.

The common interface is defined in the \fBpfmlib.h\fR header file. The Itanium specific interface is
in \fBpfmlib_itanium.h\fR. The \fBpfmlib_itanium2.h\fR provides the Itanium2 interface.

The common interface is described in individual man pages. There is one man page
for each model specific set of interfaces.

.SH AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
.SH SEE ALSO
pfmlib_itanium(3), pfmlib_itanium2(3) and the set of examples shipped with the library
.PP
